% -----------
% Copyright 2013-2014, Andrew Lindesay
% Distributed under the terms of the MIT License.
% -----------

\section{Configuration}
\label{config}

The application server is configured using a standard java properties file.  This same format is used in different ways for either an actual deployment or a development environment.

A typical java properties file has the following general form;

\begin{verbatim}
# Comment
key1=value1
key2=value2
\end{verbatim}

There are a number of keys which are described below.

\subsection{General}

\subsubsection{\tt architecture.default.code}

This configuration setting defines the code of the default architecture that should be shown.  Example values might be ``x86\_gcc2'' or ``ppc''.

\subsubsection{\tt deployment.isproduction}

This configuration setting can have a value of ``true'' or ``false''.  When false, the system will display a warning message on the user interface to indicate that the deployment is non-production.

\subsubsection{\tt pkgversion.viewcounter.protectrecurringincrementfromsameclient}

This configuration setting can have a value of ``true'' or ``false''.  When true (the default), the system will make basic efforts to protect against one client repeatedly incrementing a package version's view counter.  This might happen when a user navigates to view a package and then navigates away and back again.  With this value set as true, within a window of time, these two visits would be considered to be the same in terms of incrementing the view counter.

\subsubsection{\tt optipng.path}

This is a system path to the \href{http://optipng.sourceforge.net/}{OptiPNG} tool.  This tool can be used in some situations to optimize PNG data; for example when configuring icons for packages.  An example value might be ``{\tt /usr/local/bin/optipng}''.

\subsection{Package Rating Derivation}

See \ref{userrating} for further details on how the package rating derivation algorithm uses these values to calculate packages' ratings.

\subsubsection{\tt userrating.aggregation.pkg.versionsback}

This value is the number of versions back in the past from which the derivation will consider user ratings.  This value defaults to 2.

\subsubsection{\tt userrating.aggregation.pkg.minratings}

When deriving an aggregate rating for a package, if there are not enough user ratings then the package will have no rating.  This value is the minimum threshold and has a default value of 3.

\subsection{Database-Related}

\subsubsection{\tt jdbc.driver}

Class name of the JDBC driver employed.

example : \framebox{\tt org.postgresql.Driver}

\subsubsection{\tt jdbc.url}

JDBC connect URL to the main database

example : \framebox{jdbc:postgresql://localhost:5432/haikudepotserver}

\subsubsection{{\tt jdbc.username} and {\tt jdbc.password}}

Database user's username and password

\subsubsection{\tt flyway.migrate}

Set this to {\tt true} if you would like database schema migrations to be applied automatically as necessary.  Generally this should be configured to {\tt true}.

\subsubsection{\tt flyway.validateOnMigrate}

Set this to {\tt false} if you want the system to validate schema migrations.  This can be helpful at development time when the schema is in flux, but should be {\tt true} in production.

\subsubsection{\tt cayenne.query.cache.size}

Cayenne is the ORM system behind this application.  Some queries' results are cached and this configuration item allows the size of the query cache to be configured.

\subsection{Web-Related}

\subsubsection{\tt jawr.debug.on}

This configuration relates to the \href{https://jawr.java.net/}{JAWR} debug setting.  It will default to ``false'.

\subsubsection{\tt baseurl}

This is the base URL used to formulate URLs to be sent out that can be used to return back to the system.

For example; this might be used to create the URL used to manage the password reset process.  The URL base is included in the email body to users who have requested a password-reset.  This has to be configured because the application itself does not know the path by which the HTTP request had reached it.

In the case of a development environment, this base URL might be something like;

\framebox{http://localhost:8080}

Note that this value should have no trailing slash.

\subsection{Token Bearer Authentication}

See \ref{token-bearer-authentication} for details regarding this area.

\subsubsection{\tt authentication.jws.sharedkey}

This shared key is used to sign the authentication tokens transmitted between the server and the client.  This value is optional.  If it is not supplied then a random shared key will be used for each launch of the application server.  Non-configured keys will not work where two or more load-balanced application servers are employed.  Any random value can be used for this and a possible way to create values is to use the command {\tt uuidgen}.

\subsubsection{\tt authentication.jws.issuer}

This identifies the system that has produced a given token and is required.  It should be a string with the suffix ``.hds''.  For example ``{\tt staging.hds}''.

\subsubsection{\tt authentication.jws.expiryseconds}

This configuration value defines how many seconds a token will be able to be used before it expires.  This value is optional and a sensible default will be employed in its absence.

\subsection{Email}

Email infrastructure is used for;

\begin{itemize}
\item Password reset (forgot my password)
\end{itemize}

\subsubsection{\tt smtp.host}

The host name or IP address of the SMTP server.  This configuration value is required.

\subsubsection{\tt smtp.port}

The port of the SMTP server.  This configuration value is optional and will default to 25.

\subsubsection{\tt smtp.auth}

Possible values are ``true'' or ``false''.  When true, SMTP authentication will be used.  This configuration value is optional and will default to ``false''.

\subsubsection{\tt smtp.username}

This is only required when SMTP authentication is configured.

\subsubsection{\tt smtp.password}

This is only required when SMTP authentication is configured.

\subsubsection{\tt smtp.starttls}

Possible values are ``true'' and ``false''.  Configures the SMTP transport.  This value is optional and defaults to ``false''.

\subsubsection{\tt email.from}

This is the email address from which emails outbound from the system will be sent.  Typically this might be a ``no-reply'' email address such as ``noreply@haiku-os.org''.

\subsection{LDAP}

\fcolorbox{red}{white}{\parbox{\textwidth}{\color{red}The LDAP integration is not intended to be used at this point in time.}}

\subsubsection{\tt ldap.host}
\subsubsection{\tt ldap.port}
\subsubsection{\tt ldap.user.dn}
\subsubsection{\tt ldap.password}
\subsubsection{\tt ldap.people.dn}

\section{Logging Configuration}

The application logging uses the \href{http://www.slf4j.org/}{SLF4J} logging framework.  This is backed by the \href{http://logback.qos.ch/}{Logback} logging system.  When formatting log lines, it is possible to add additional meta data from the application server.  This is known as the ``MDC''.  Presently supported;

\begin{tabular}{ | l | l | }
\hline
Key & Description \\
\hline
{\tt authUserNickname} & The nickname of the presently authenticated user \\
{\tt userAgent} & The User-Agent HTTP header related to the current request \\
{\tt userAgentCode} & This is a short code to describe the user agent in brief \\
\hline
\end{tabular}